/*
RPC服务定义和接口

	为分布式系统中的跨节点通信提供规范接口和数据结构，适用于需要多个服务节点协同工作的场景（如游戏服务器集群、微服务架构等）

		RPC 通信的 “骨架”：
		Service接口定义了 “能做什么”（远程调用、广播）；
		Message定义了 “传输什么”（带路由的数据）；
		NodeInfo定义了 “谁在参与通信”（节点的标识和网络信息）。
		它们共同为分布式系统中的跨节点协作提供了标准化的基础，使得不同功能、不同位置的节点能够高效、可靠地通信。

2025/10/08
增加rpc服务的 client，server
*/
package rpc

import "context"

/* //* RPC服务定义，提供Service接口规范和Message数据结构，为分布式系统中的跨节点通信提供标准接口 */

// RPC 服务接口
//
// 	Service接口是 “依赖倒置” 设计原则的体现 —— 上层业务只需依赖此接口，无需关心底层是用 TCP、gRPC 还是其他协议实现。例如：可以有TCPRPCService、GRPCService等不同实现，均满足Service接口，业务代码无需修改即可切换通信方式。
type Service interface {
	// 调用远程方法
	//
	// 	实现 “点对点” 的远程方法调用（类似本地函数调用，但执行在远程节点）
	// 	典型场景：玩家 A 在节点 1 发起 “查询玩家 B 信息” 请求，通过Call调用节点 2 的用户服务，获取结果后返回。
	// 	参数：
	// 	ctx context.Context：上下文，用于传递超时控制、请求元数据（如追踪 ID），支持并发控制（如取消请求）。
	// 	route uint32：路由 ID，与之前Packet中的Route作用一致，用于指定消息归属的业务模块（如 “玩家战斗”=100，“聊天”=200）。
	// 	data []byte：请求数据（二进制），通常是序列化后的业务参数（如 protobuf、JSON 字节流）。
	// 	返回值：
	// 	远程节点的响应数据（[]byte）和可能的错误（如超时、路由不存在）。
	Call(ctx context.Context, route uint32, data []byte) ([]byte, error)
	// 广播消息到所有节点
	//
	// 	实现 “一对多” 的消息广播，将消息发送到集群中所有节点（或指定类型的节点）。参数与Call类似，区别是无返回值（广播通常不需要每个节点单独响应）。
	// 	典型场景：游戏服务器中 “全服公告”，通过Broadcast将公告消息发送到所有游戏节点，再由各节点推送给本地玩家。
	// 	参数：
	// 	ctx context.Context：上下文，用于传递超时控制、请求元数据（如追踪 ID），支持并发控制（如取消请求）。
	// 	route uint32：路由 ID，与之前Packet中的Route作用一致，用于指定消息归属的业务模块（如 “玩家战斗”=100，“聊天”=200）。
	// 	data []byte：请求数据（二进制），通常是序列化后的业务参数（如 protobuf、JSON 字节流）。
	Broadcast(ctx context.Context, route uint32, data []byte) error
}

// RPC 消息结构
//
// 	封装 RPC 通信中的消息内容，是数据传输的 “容器”
// 	当节点 A 向节点 B 发送 RPC 请求时，会将route和data打包成Message结构体，序列化后通过网络发送；节点 B 接收后反序列化出Message，根据Route找到对应的处理逻辑，再处理Data
type Message struct {
	// 路由，手动指定，不同于gin
	Route uint32 `json:"route"`
	// 数据
	Data []byte `json:"data"`
}

// 节点信息
//
// 	描述分布式集群中一个节点的基本信息，是服务发现、负载均衡、节点管理的基础
// 	使用场景：
// 	服务注册：节点启动时向 “注册中心” 提交NodeInfo，告知自己的存在和能力。
// 	服务发现：客户端需要调用 RPC 时，从注册中心获取目标节点的NodeInfo（地址和端口），才能发起请求。
// 	负载均衡：根据Capacity和当前负载，选择合适的节点处理请求（如优先选择剩余容量多的节点）。
type NodeInfo struct {
	// 节点唯一标识（如 “game-node-1”“chat-node-2”），用于在集群中唯一区分节点
	ID string `json:"id"`
	// 节点类型（如 “game”“chat”“db”），用于区分节点的功能角色（不同类型节点处理不同业务）
	Type string `json:"type"`
	// 节点的网络地址（如 IP）和端口，用于建立网络连接（RPC 调用的目标地址）
	Address string `json:"address"`
	Port    int    `json:"port"`
	// 节点容量（如最大承载玩家数、每秒最大请求数），用于负载均衡（如将请求分配给负载较低的节点）
	Capacity int `json:"capacity"`
}
